docs(api): daily audit 2026-10-16 — RUM issue resolve mode, chat-bound Automation rules - #1061

Summary

Daily audit of the public OpenAPI surface (--mode generate --scope all --auto) plus the minimal-diff repair of two source-backed drifts that landed after the docs baseline.

• Docs baseline: flashduty-docs main @ 23d063b1 (2026-10-15T22:34:12+08:00 / 14:34Z).
• Audit window: every implementation repo commit with commit time after that baseline (origin/main of fc-pgy, fc-event, fc-oncall, fc-rum, fc-statuspage, monit-webapi, fc-datasource, go-pkg, fc-safari, monit-edge, fetched fresh).
• Public surface diff: registry rows with Auth == "all" and a path that does not start with /event/push/ = 371 rows; the five split specs hold 370 operations. The single difference is the already-known POST /channel/incident/daily-counts (see Unresolved). No operation was added or removed, so docs.json and both api-catalog.mdx files were deliberately not touched.

Changes

1. RUM issue resolve mode (fc-rum, PR #294 merged as e60de00, 2026-10-16T12:00+08:00)

Go evidence on origin/main:

• cmd/server/controller/issue/update.go — issueUpdateInput gained
  ResolveMode string json:"resolve_mode" binding:"omitempty,oneof=any version", applied only while status == resolved; when omitted there the stored mode becomes any (types.ResolveModeAny).
• types/issue.go — IssueItem gained ResolveMode string json:"resolve_mode" between resolved_by and created_at. logic/issue/regression.go#reopensOnRecurrence treats any as "reopen on any recurrence" and everything else — including the empty value written by inserts before the mode shipped (logic/issue/issue.go: a struct insert writes '' over the column default) — as "reopen only on an unseen version".

Emitted:

• RumIssueUpdateRequest.properties.resolve_mode — string, enum [any, version], optional.
• RumIssueItem.properties.resolve_mode — string, enum ["", any, version] (the empty enum member documents the legacy rows, matching the existing environment_kind convention in the same files).
• Response examples of /rum/issue/info and /rum/issue/list, and the request example of /rum/issue/update now carry the field.

2. Chat-bound Automation rules (fc-safari, PR #1551 merged as 3206cd7e, 2026-10-16T12:44+08:00)

Go evidence on origin/main (3206cd7e is what brought commit 34a3654c, 2026-10-14, onto main — it is not an ancestor of 3206cd7e^1):

• cmd/api/automation/automation.go#CreateRuleRequest — TeamID int64 became *int64 ("omitted means inherit the source conversation scope, while an explicit zero asks for personal scope"), and a new RunIn *string json:"run_in" binding:"omitempty,oneof=current-chat web" was added.
• types/automation.go#AutomationRuleItem — gained ExecutionPlace string json:"execution_place" (no omitempty) and ExecutionLocation *AutomationExecutionLocation json:"execution_location,omitempty"; logic/transfer.go always fills both (config.ExecutionPlace(), config.PublicLocation(row.RunScope, row.TeamID)).
• types/automation_execution.go — new AutomationExecutionLocation type.

Emitted:

• AutomationRuleCreateRequest.properties.team_id — ["integer","null"] (was integer) and a corrected description; the previous text ("0 or omitted means a personal rule") is no longer true.
• AutomationRuleCreateRequest.properties.run_in — ["string","null"], enum [current-chat, web].
• AutomationRuleItem.properties.execution_place — string, enum [im, web_console], added to the item's required (Go has no omitempty).
• AutomationRuleItem.properties.execution_location — $ref: AutomationExecutionLocation.
• New components.schemas.AutomationExecutionLocation — place, run_scope, team_id, platform, conversation_mode, chat_name, description; required: [place, run_scope, team_id, description] (the four fields without omitempty). No enum is invented for platform / conversation_mode — the source declares no closed value set for them.
• The rule-create request example and the four rule item response examples now carry run_in / execution_place / execution_location.

Diff discipline (iron rule 1)

• Baseline for every edit was read with git show HEAD:<path>; the worktree was never used as an input.
• Key order: insert-only, verified. The HEAD key-path sequence is a subsequence of the new one in all six files (no reordering, no cosmetic churn). The consolidated files and the RUM split keep their alphabetical convention; the Safari split keeps its type-first convention.
• git diff --stat: 6 files, 512 insertions / 12 deletions. The 12 deletions are the old team_id type: "integer" line (replaced by the two-member array) and the old team_id description line, in the four files that carry the create request.
• Every added leaf was enumerated and is listed above; no other leaf was added, removed, or changed.
• Validation: all six files load with python3 -c "import json; json.load(open(path))"; 0 dangling $ref; 0 structural EN/ZH differences (comparison with human-facing text stripped) across all five modules; 0 integer epoch-looking fields missing Unix/epoch/timestamp wording; 0 *_ms integer fields missing milli wording.

Navigation and catalog

docs.json and en|zh/openapi/api-catalog.mdx were not modified: the path sets of all six spec files are byte-identical to HEAD (370 → 370, rum 41 → 41, safari 53 → 53). The skill's reachability check prints none for both modules in the nav and in both catalogs, i.e. the pre-existing coverage is unaffected.

mint broken-links could not be run — mint is not installed in this environment. The change only edits existing operations, so no new link is introduced.

Unresolved

• POST /channel/incident/daily-counts (channel:read:incidentDailyCounts, Auth: all) is in the fc-pgy registry but has no handler on fc-event origin/main — cmd/server/routes.go:146 and logic/incident/daily_counts.go exist only on origin/dev. Per the skill it is not written into any spec; the row belongs to whoever decides to ship the handler or change the row's Auth. This is the only registry-vs-docs difference and it is unchanged from the previous rounds.

Recorded, not fixed this round

These are pre-existing docs-vs-Go gaps or committed internal inconsistencies, all outside the audit window; each would need its own decision (and, for the last two, a new schema), so they are not folded into this windowed diff.

• safari automation schemas are missing a family of fields that already exist on fc-safari origin/main and are described in en|zh/ai-sre/automations.mdx:
  • AutomationRuleCreateRequest / AutomationRuleUpdateRequest: oncall_incident_merge_similar, war_room_trigger_enabled, war_room_channel_ids, war_room_severities.
  • AutomationRuleItem: the same four plus war_room_trigger_id and last_run (would need a new AutomationRuleLastRun schema).
  • AutomationRunItem: execution_place, joined_session_id, joined_session_name.
• POST /channel/escalate/rule/reorder changed its input on fc-event origin/main (ec2b38e4e: new_priorities/priority/rule_id → drag_rule_id/target_rule_id) but that row is Auth: jwt in the registry, so it is not public surface and is not documented here.
• fc-event PR #3156 added /ai-sre/chat-automation/{resolve,turn,execution-check}; those routes live in fc-event's own engine group and are not registered in fc-pgy, so they are not public.
• fc-safari SettleRunRequest.status gained skipped; no registered public route uses that request.
• monit-webapi edge-push telemetry (PR docs(api): sync public RUM endpoints #162), fc-datasource IM person-link sweep, fc-oncall DingTalk notify: no public request/response struct changed.
• Internal split-vs-consolidated drift, unchanged by this PR and left alone deliberately: the seven /incident/work-item/* split response examples lack assignees (consolidated has it); DutyError.reason exists only in consolidated under x-flashduty-preserve-absence: true; ServiceUnavailable exists only in consolidated for on-call/rum/platform/safari and is referenced by no split operation; the Safari split's components.responses differ from the other five files in five entries (BadRequest, Forbidden example names/messages, TooManyRequests description, and NotFound/ServiceUnavailable absent).
• Open PR #1051 (docs/app-key-leak-remediation) is still open and stale; not used as a source.
• Skill config defect (report only, per the "do not patch the skill body" policy): mapping.yaml declares on-call/calendar as providers: [event] pointing at fc-event, while the eight /calendar/* rows are provider pgy and the handlers live in fc-pgy. Running analyze strictly by that mapping would silently drop those eight operations.

Examples

/rum/issue/update, /rum/issue/info and /rum/issue/list gained the new field only; their existing values are untouched. The Safari additions (run_in: "web", execution_place: "web_console", execution_location: {place, run_scope, team_id, description}) are constructed from the schema and the Go source, not captured from a live API: this environment has no app_key credential for https://api-dev.flashcat.cloud. They reuse the IDs already present in those examples so request and response stay coherent.